==============================================================================
= Alpha Commands
==============================================================================

In this list of routines, text between '<' and '>' is a placeholder for a 
required parameter, text between '[' and ']' is a placeholder for an 
optional parameter, and the '|' signifies a choice of two or more 
alternatives.  A '+' signifies that the previous symbol can be present one 
or more times, while a '*" means zero or more times.  Some commands have no 
parameters, and are only expected to be called interactively.

The following are Alpha-specific tcl routines:

Window related commands:
 
= Basic insertion position queries

 getPos [-w <win>] - return the current insertion point
 lineStart <pos> - return the position of the start of the line 'pos' is on.
 matchIt <brace char> <pos> [<limit>] - Return pos of matching brace. 
	Recognizes parenthesis, square brackets, and curly braces.  Optional
	third argument specifies how many characters to search.  The brace char
	passed to this command should be the one whose partner you wish to find
	(not the one you want to search for).  When searching backwards (i.e.
	when trying to match a right brace), 'pos' should be the last position
	which could be a successful match, and not the position of the right
	brace itself (i.e. it will usually be the position just before the right
	brace itself).  For example if you have the text "abc ()" so that ')' is
	at position 5, then 'matchIt ) 5' will fail to match, but 'matchIt ) 4'
	will correctly return '4'.
 minPos - returns the first position in the current window.  This will
    normally be '0' in Alpha 7.x, but for compatibility with Alphatk (in
    which it is 1.0) should not be so assumed.
 maxPos [-w <win>] - returns the position of the last character in the front
    window.
 nextLineStart <pos> - return the position of the start of the next line after
    position 'pos'.
 pos::diff <pos1> <pos2> returns the number of characters between the two 
    positions in the current window.
 pos::math <pos> ?+/- offset? ...  returns that position which is given by
    moving the given number of characters backwards or forwards in the current
    window.  Any number of offset arguments may be given, with or without
    spaces separating the arguments.  For future compatibility pos::math
    should be used in preference to numerical addition: positions cannot
    be assumed to be simple integers.
 pos::compare <pos1> <comparison> <pos2> returns 1 or 0 depending on whether
    the given comparison is true or not.  Valid comparisons include 
    ==, !=, <, >, <=, >= etc.  For future compatibility, pos::compare
    should be used in preference to a direct, numerical comparison.
 posToRowCol <pos> - converts from absolute position to row, col.
 rowColToPos [-w <win>] <row> <col> - converts to absolute position.
    Accepts optional -w parameter that allows window to be specified.

= Basic insertion position movement

 backwardChar - moves insertion one char back
 backwardWord - moves insertion one word back
 backwardWordSelect - extend selection one word back
 beginningOfBuffer - move insertion to the beginning of the buffer
 beginningOfLine - move insertion to the beginning of the line
 endOfBuffer - move insertion to the end of the buffer
 endOfLine - move insertion to the end of the line
 exchangePointAndMark - exchange the current 'mark' w/ the current insertion point
 forwardChar - move insertion one character forward
 forwardWord - move insertion one word forward
 forwardWordSelect - extend selection one word forward.
 goto <pos> - go to the position 'pos' in the current window.
 gotoLine - prompt for a line in the current window and jump to it
    (used by clicking on line/row indicator in the status bar window).
 gotoMark - go to named mark, use 'mark' in macros.
 gotoNamedMark - present the user with a dialog containing all marks
    from all open windows.
 gotoTMark <name> - go to the temporary mark 'name'.
 matchBrace - moves the insertion point to the character that matches 
    the character after the current insertion point
 nextLine - move insertion point to next line
 nextSentence - go to next sentence ("textFill.tcl").
 previousLine - move insertion point to the previous line
 prevSentence - go to previous sentence ("textFill.tcl").

= Basic text manipulation

 deleteText <pos1> <pos2> - remove text between 'pos1' and 'pos2'
 getText [-w <win>] <pos1> <pos2> - return the text between 'pos1' and 'pos2'. 
    '-w' can be used to specify a window.
 insertText [-w <win name>] <text>* - Insert 'text' at the current insertion
    point. Mark is unchanged.
 lookAt [-w <name>] <pos> - return the 'pos'th character of the current file,
    or the file named by <name> if the '-w' option is specified.
 replaceText ?-w win? <pos1> <pos2> [text]+ - replaces the text between 'pos1'
    and 'pos2' with 'text', where 'text' can be any number of arguments. 
    Leaves insertion at end, mark at beginning of inserted text. 

= Selection manipulation and creation

 balance - selects smallest set of parens, braces, or brackets that encloses
    the current selection
 backwardCharSelect - extends selection one char back
 beginningBufferSelect - extend selection to the beginning of the buffer
 beginningLineSelect - extend selection to the beginning of the line
 clear - clear selected text
 deleteSelection - delete current position, don't save
 endBufferSelect - extend selection to the end of the buffer
 endLineSelect - extend selection to the end of line
 forwardCharSelect - extend selection one character forward
 getSelect - return the currently selected text, if any.
 markHilite - This is the 'Hilite' from the 'Edit' menu. If there is a
    currently hilited selection, the selection is unhilited, leaving the mark
    and the insertion point around the old selection. If there is not a
    selection, the region between the insertion point and the mark is selected.
 nextLineSelect - extend selection to the next line
 prevLineSelect - extend selection to the previous line
 rectMarkHilite - creates a rectangular selection between the mark and
    the insertion point.
 select [-w <win>] <pos1> <pos2> - selects the text between 'pos1' and 'pos2'.
 selEnd [-w <win>] - returns the end of the hilited selection, or the current
    insertion point if no text is selected.
 setMark - set the current mark to the insertion point

= Clipboard/scrap handling
  
 copy - copy region
 cut - deletes and saves region
 getScrap - returns system TEXT scrap.
 paste - insert the last chunk of text created by 'cut' or 'copy'
 putScrap [<string>]+ - Concatenate strings together into the system 
    scrap.  The scrap can be appended to through calls of the form 'putScrap
    [getScrap] " another word"'.

= Various textual manipulations
 
 backSpace - delete selection, or a single char if no selection.
 backwardDeleteWord - deletes previous word
 capitalizeRegion - capitalize first word in selected region 
 capitalizeWord - capitalize word and move to its end
 deleteChar - delete char AFTER cursor
 deleteWord - delete word after cursor
 downcaseRegion - changes all letters to lowercase in current region
 downcaseWord - changes all letters to lowercase in current word
 killLine - kill text from insertion point to the end of the line. If the line
    has no text, delete the line and move succeeding lines up one.
 oneSpace - converts whitespace surrounding insertion into a single space.
 openLine - insert a new line following the current one and move the insertion
    point to it
 spacesToTabs - convert spaces in selection to tabs
 tab - insert a tab
 tabsToSpaces - convert tabs in selection to spaces.
 upcaseRegion - convert all letters to uppercase in the current region
 upcaseWord - convert all letters to uppercase in the current word
 wrap - see the section on "Fill" routines.
 wrapText -
 yank - insert the last piece of deleted text of less than 1k. 
    Consecutive deletes are concatenated together.
 zapInvisibles - removes chars < ascii 32, except for LF's and CR's.

= View/insertion interaction

 blink <pos> - blink cursor at 'pos'
 centerRedraw - redraw window with current line in the middle.
 display [-w <win>] <pos> - move pos's line to top of screen.
 insertToTop - make the line that the insertion point is on the first line
    shown, and display the current line number along w/ the total number of
    lines in file
 moveInsertionHere [-last] - move the insertion point to the first (or last)
    line displayed
 pageBack - display prev screenful, move the insertion point if 
    'moveInsertion' enabled
 pageForward - display next screenful, move the insertion point if
    'moveInsertion' enabled
 scrollDownLine - same action as that which occurs when the down arrow in the
    vertical scrollbar is selected
 scrollLeftCol - same action as that which occurs when the left arrow in the
    horizontal scrollbar is selected
 scrollRightCol - same action as that which occurs when the right arrow in
    the horizontal scrollbar is selected
 scrollUpLine - same action as that which occurs when the up arrow in the
    vertical scrollbar is selected

= Dialogs for querying the user.
 
 alertnote <message> - display 'message' in a standard OS alert box.
 askyesno [-c] <prompt> - display 'prompt' in an OS alert box with the push
    buttons Yes and No. The command will return the string "yes" or "no". 
    The '-c' flag specifies that a cancel button be used as well.
 buttonAlert <prompt> [<button>] - create a dialog w/ the specified buttons,
    returning the one selected.
 colorTriple [<prompt>] [<red> <green> <blue>] - prompts the user to choose 
    color. If specified, the input RGB value is used as the initial color on 
    the colorpicker.
 dialog [<-w width>|<-h height>|<-b title l t r b>|<-c title val l t r b>|
            <-t text l t r b>|<-e text l t r b>|<-r text val l t r b>|
            <-p l t r b>]+ 
    Create and display a dialog.  '-w' and '-h' allow width and height of
    dialog window to be set.  '-b', '-c', '-r', '-t', '-e' and '-p' allow
    buttons, checkboxes, radio buttons, static text, editable text and gray
    outlines to be created, respectively.  All control types (except gray
    outlines) require specification of a title or text, together with left,
    top, right, and bottom coordinates.  Checkboxes and radioboxes have an
    additional parameter, the default value.  At least one button must be
    specified.  The return value is a list containing resulting values for
    all buttons, radioboxes, checkboxes, and editable textboxes (static text
    is ignored).  Buttons have value '1' if chosen, '0' otherwise.  The
    dialog box exits at the first button press.
 findFile [<path>] - open a file in a new window. An optional path parameter
    specifies a default directory or file.
 get_directory [-p <prompt>] - display a standard OS file dialog and request
    the user select a folder. The command will return the selected folder's
    full path name, or an error if the Cancel button was selected.
 getfile [<prompt>] [<path>] - display an SFGetFile() and return the full
    path name of the selected file, or an error if CANCEL button was selected.
    An optional path parameter specifies a default directory or file.
 getline <prompt> <default> - display an OS alert box with prompt displayed, a 
    text edit field with default initially in the field, and with the push 
    buttons OK, Cancel.. The command will return the text entered into the 
    text edit field by the user, or an empty string if the user selected the 
    Cancel button. 
 listpick [-p <prompt>] [-l] [-L <def list>] <list> - display a dialog with
    the list displayed in a List Manager list.  If the user presses the
    Cancel button, an empty string is returned.  If the user selects the Open
    button, or double clicks an item in the list, that item will be returned.
    If '-l' is specified, than the return is a list of items.
 prompt <prompt> <default> [<name> <menu item>*] - prompt dialog to 
    the user with a prompt string and a default value.  The prompt dialog
    can optionally include a popup menu specified by 'name' and the
    succeeding strings.  Selection of the popup menu items inserts the item
    text into the editable dialog item.  'Prompt' returns the value of the
    editable item.  If the 'Cancel' button is selected, the tcl returns an
    error and your script will be stopped unless you execute the command
    from 'catch'.
 putfile <prompt> <original> - display an SFPutFile() and return the full
    path name of the selected file, or an empty string if CANCEL button was
    selected. Original is the default name displayed for the user.
 setFontsTabs - bring up font and tab dialog
 setRGB - 

= Search in a window

 search  [options] <pattern> <pos> - search for 'pattern' from position 'pos'.
    Valid options include

      -f <num>		- go forward?
      -r <num>		- regular expression?
      -s			- save previous search string and search flags.
      -i <num>		- ignore case?
      -m <num>		- match words?
      -n			- failed search still returns TCL_OK, but null string.
      -l <limit>	- limit on how search goes.
      --	 		- next arg is the pattern.

    If the search succeeds, a list of two positions will be returned.  The
    first is the starting position of the match, the second is one past the
    last character.  If no '-n', TCL_ERROR returned.  See also
    performSearch.  To search from the beginning of the buffer, use
	'search -s -f 1 ... [minPos]' and to search backwards from the end,
	use 'search -s -f 0 ... [maxPos]'.

= Using search dialog-equivalents from Tcl.

 enterReplaceString - use current selection, if any, for future replacements
    (in search dialog).
 enterSearchString - use current selection, if any, for future searches.
 find - bring up the find dialog
 findAgain - repeat search forward
 findAgainBackward - repeat search backward
 findInNextFile - search next file.
 performSearch  [options] <pattern> <pos> - as for 'search' but also selects
    the range of characters which are found, and ensures Alpha's internal
    state is consistent for following replace/replaceAll/...  commands.
 replace - replace the current selection
 replaceAll - replace all further occurrences in the current file or set
    of files.
 replace&FindAgain - replace the current selection and find next occurrence.
 replaceString [<str>] - specifies replacement string. Returns current 
    replacement string if no arg.
 searchString [<str>] - allows search string to be specified. Returns 
    current searchstring if no arg.
 isearch - incremental search: searches w/o a dialog, searches as you type
    the search pattern.  Does not do regular expression searches.  'matchWords'
    automatically set to false.
 rsearch - reverse incremental search, see 'isearch'.

= Basic window creation and file-interaction

 edit [-r] [-m] [-c] [-w] [-g <l> <t> <w> <h>] <name> - Open a file in new 
	window.  '-c' means don't prompt for duplicate win if file already
	open.  '-r' means open the file read-only.  '-m' means omit the
	function titlebar menu and present only the marks titlebar menu, which
	is labeled with the contents of 'markLabel'.  The '-g' option allows
	left and top coords to be specified, plus width, and height.  All or
	none.  '-w' allows you to bypass the "Wrap" dialog for files with long
	rows.
 new [-g <l> <t> <w> <h>] [-n <name>] - opens an untitled window. Can
	optionally provide left and top coordinates, plus width and height.
	All or none.
 revert ?-w win? - revert the file to its last saved version
 save - save current window
 saveAs ?-f? [def name] - save current window with new name. Optionally 
	takes a default filename.  Returns complete path of saved file, if ok hit,
	otherwise TCL_ERROR returned.  If '-f' flag given, then we force the save
	without any standard-file dialog.

= Window manager

 bringToFront <winName> - Bring named window to front.
 closeAll - close all windows
 closeFloat - close the top floating window.
 displayMode <mode> - Up to four characters of the 'mode' string are 
    displayed in the status line at the bottom of a window.
 float -m <menu> [<-h|-w|-l|-t|-M> <val>] [-n winname] [-z tag] -
    Takes a created menu (not necessarily in the menubar), and makes a floating
    window out of it.  Returns integer tag that is used to remove the window. 
    NOT DYNAMIC! W/ no options returns all currently defined menus.  Displayed
    w/ system floating window WDEF if system 7.5, plainDBox otherwise.  -h
    through -M change width, height, left margin, top margin, and margin
    between buttons.  -z allows a ten-char tag to be specified for
    'floatShowHide'.
 float [-n <window name>] <resID> [<resID> ...] - make a little floating window
     containing small icons with the specified resource IDs.
 floatShowHide <on|off> <tag> - Shows or hides all floats w/ specified tag.
    Tags of current modes are automatically shown/hidden.
 getGeometry [win] - return a TCL list containing the left edge of the current
    window, the top, the width, and height.
 getMainDevice - return a list containing the left, top, right, and bottom
    of the rectangle defining the main device.
 getWinInfo [-w <win>] <arr> - Creates an array in current context 
    containing info about either the current or a specified window.  Array has
    fields 'state', 'platform', 'read-only', 'tabsize', 'split', 'linesdisp'
    (num lines that can be seen in the window), 'currline' (first line
    displayed), and 'dirty'.
 icon [-f <winName>] [-c|-o|-t|-q] [-g <h> <v>] - Having to do w/ 
    iconifying windows.  '-c' means close (iconify) window, '-o' open, '-t'
    toggle open/close, '-q' returns either a '1' for an iconified window or a
    '0' for an uniconified window, and '-g' moves the icon to horizontal
    position <h> and vertical position 'v'.  Options are executed as they are
    parsed, so the '-f' option, if present, should always be first.
 killWindow - kill current window
 mousePos - Returns list <row,col> of mouse position, if the mouse is 
    currently over the active window.  Otherwise, return error (catch w/
    'catch').
 moveWin [win name] <left> <top> - moves current or specified window. 
    The window name can be "StatusWin".
 nextWindow - select next window
 otherPane - If window is split, select the other pane.
 prevWindow - select previous window
 saveAll - save all currently open windows.
 setWinInfo [-w <win>] <field> <arg> - Sets a piece of data about either 
    the current or a specified window.  Settable fields 'platform', 'state',
    'read-only', 'tabsize', 'dirty', and 'shell'.  'shell' means that dirty
    flag ignored and undo off.
 sizeWin [win name] <width> <height> - sets size of current or specified window.
    The window name can be "StatusWin", although only the width can be changed.
 splitWindow [percent] - toggle having window split into two panes. 
    Optional arg specifies percent of window to allocate to the first pane. 
 toggleScrollbar - toggles horizontal scrollbar on frontmost window. 
    Will not succeed if scrollbar scrolled.
 unfloat <float num> - removes specified floating window. W/ no options 
    lists all floating windows.
 wins - return window boundaries for all windows.
 winNames [-f] - return a TCL list of all open windows. If '-f' option 
    specified, complete pathnames are returned.
 zoom - zooms the current window

= Menu creation/manipulation

 addHelpMenu <item> - add 'item' to the OS Help menu. No menu conversion
    done, i.e. all items appear as given without being massaged in any way.
    In Alpha8/tk, 'item' can be a submenu created with the 'Menu' command.
 addMenuItem [-m] [-l <meta-characters>] <menu name> <item name> - Convert
    item to menu form and add to specified menu.  If '-m' specified, menu form
    conversion not done.  The '-l' option allows you to use menu meta
    characters as text of menu items.  If the '-l' option is used, the
    <meta-characters> string is interpreted for menu item attributes, and
    meta-characters in <item name> are included in the menu item text
    literally.  For example:
      addMenuItem -m -l "/B" "Hello/C" 
    would appear as the text "Hello/C" in the menu, and have "B" as its 
    command equivalent.
 deleteMenuItem [-m] <menu name> <item name> - Convert item to menu form 
    and delete from specified menu.  If '-m' specified, menu form conversion
    not done.
 enableMenuItem [-m] <menuName> <item text> <on|off> - Either enable or 
    disable the menu item of user menu 'menuName' that has text '<item text>'. 
    Note that unless the menu is not only created, but also already inserted,
    this command has no effect.
 insertMenu <name> - insert the previously created user menu 'name' into 
    the menuBar. 
 markMenuItem [-m] <menuName> <item text> <on|off> [<mark char>] - 
    Either mark or unmark the menu item of user menu 'menuName' that has text
    '<item text>'.  Note that unless the menu is not only created, but also
    already inserted, this command has no effect.
 Menu [-i <num][-m] [-M <mode>]  [-n <name|num>] [-p <procname>] [-s] <list> -
    Defines a new menu named 'name' (if provided w/ '-n' option) with items
	'list'.  The menu is not yet inserted into the menubar.  The menu
	commands may be nested for heirarchical menus, such as in the filesets
    menus.  By default Alpha massages the item names in the 'list' to make them 
    look better in the menus.

      -c            Ignore any menu meta-chars. Can also be done on a per-item
                    basis by appending an ampersand ('&') to the end of an item.
                    (Buggy in Alpha7.)
      -m            No menu form. If not supplied, each menu item is split into 
                    words at each capitalized letter.
	  -M <mode>     Specifies that any bindings created by the menu are 
					specific to a given mode.  This is important because
					mode-specific bindings over-ride global bindings.
      -n <name>     Name the menu. Not necessary for submenus.
	  -n <num>      Resource id of icon suite to use for menu title. 'ics#' 
					is the only resource that is really necessary.
      -p <name>     The tcl proc named by 'name' is called w/ the menu's name
                    and the item's contents when the item is chosen.
	  -s            Use system menu definition proc (faster).

 removeMenu <name> - remove menu 'name' from menubar, except those 
    specified by previous 'makeMenuPermanent' calls.

= Inter-application communication

 AEBuild [<flags>] <app (name|creator)> <aesuite> <aeevent> [<event parameters>]*  -
    Build and send an apple-event.  'AEBuild' is apple's code of the same name. 
    Each "event parameter" is two parameters, a parameter type and the data for
    the parameter.  See the "AEGizmos" help file for more details. Flags include:

      -r            Wait for reply.
      -q            Queue reply, in which case 'handleReply' (in appleEvents.tcl)
                    is called with the reply as a parameter.
      -t <timeout>  Specifies the timeout in ticks.

 dosc [<-c 'sign' | -n appName>] [-k 'clas'] [-e 'evnt'] <-s string | -f fileName> [<-t timeout|-r>] -
    Send an AppleEvent, by default class 'misc', event 'dosc'.

      -c 'sign'     "sign" is a four-letter creator signature of a
                    running application.
      -n appName    "appName" is the name of a running application.
      -k 'clas'     "clas" is a four-letter event class.
      -e 'evnt'     "evnt" is a four-letter event class.
      -s string     "string" is the text of a script to send to the other app.
      -f fileName   "fileName" is the complete or relative pathname of a file
                    the other application should execute.
      -t timeout    "timeout" is the number of ticks Alpha should wait for
                    a response. A timeout of "0" means wait forever.
      -r            Do not wait for reply.
      -q            Queue reply.
           
    If neither of the '-c' and '-n' options is chosen, the PPC Browser is used. 
    Either '-s' or '-f' must be chosen.  Thus, you can have "Alpha 5.02" and
    "Alpha 5.02 Copy" sending Apple events to each other, or they can send
    events to a remote server such as Apple's ToolServer.
 eventHandler [class] [event] [proc] - Register 'proc' to handle the class 
    and event specified.  Class and event are each 4 char args.  'proc' takes a
    single argument that specifies the incoming event according to the syntax
    here.  There is currently no provision for a reply.
 icGetPref [<-t <type>] <pref name> - Gets preference from 
    Internet Config.  '-t' allows type to be set, '0' returns a string
    (default), '1' returns a path name, commonly used for helper apps.  A <pref
    name> of 'all' returns all valid preferences.
 icOpen - Opens Internet Config
 launch -f <name> - launch the named app into the background. Note that 
    for some yet unexplained reason, some applications (MicroSoft Word) won't
    launch completely in the background.  'launch'ing such applications won't
    insert the application into any system menu that specifies running
    applications (although "About the Finder..."  will list it.  The only way
    to get to such an app is through Alpha's 'switchTo', after which the
    application will finish launching.  The '-f' option gets around this by
    launching the application in the foreground instead.
 nameFromAppl '<app sig>' - Interrogates the desktop database for the first 
    existing app that has the desired signature.  <app sig> is four chars
    inside single quotes.
 processes - returns info of active processes. A list of lists, each 
    sublist contain a file-name, an application signature, the application
    memory size, and the number of ticks the application has been active.
 switchTo <appName> - Switches to application 'appName'.
 sendOpenEvent [filler] <app name> <file name> - Send an open doc event to 
    another currently running application.  If 'filler' is noReply, then a
    reply is not requested.  Otherwise, we wait for a reply and 'filler' is
    ignored.
 specToPathName [hex data] - given an FSSpec in hex form (as that 
    returned by aebuild, for instance, see the definition of thinkFileName in
    "thinkMenu.tcl"), return a complete pathname.

= Keyboard bindings and codes

 ascii  (see "Default Key Bindings").
 Bind   (see "Default Key Bindings").
 bindingList - return list of bindings.
 deleteModeBindings <mode> - Delete all bindings for specified mode.
 describeBinding - display the binding of the next typed key sequence. 
 getAscii - displays the ASCII code for character at current insertion point
 getChar - waits for a keystroke, returns ascii.
 getModifiers - returns current modifiers mask. "OR" of several values, 
    cmdKey                      = 0x01,      /* Bit 0 of high byte */
    shiftKey                    = 0x02,      /* Bit 1 of high byte */
    alphaLock                   = 0x04,      /* Bit 2 of high byte */
    optionKey                   = 0x08,      /* Bit 3 of high byte */
    controlKey                  = 0x10,      /* Bit 4 of high byte */
    rightShiftKey               = 0x20,      /* Bit 5 of high byte */
    rightOptionKey              = 0x40,      /* Bit 6 of high byte */
    rightControlKey             = 0x80,      /* Bit 7 of high byte */
 insertAscii - prompt for an ASCII code and insert into text.
 keyAscii - insert ascii representation (in decimal) of the keydown event,
    plus a modifier string, if necessary.
 keyCode - insert the key code along w/ a string representing and modifiers
    into the current window. Used by the Alpha Dev menu to create bindings.
 prefixChar - used to further modify the next keystroke combination, 
    in the same manner as using the shift key in the next keystroke
 startEscape - used to further modify the next keystroke combination,
    in the same manner as using the shift key in the next keystroke
 unascii (see "Default Key Bindings").
 unBind  (see "Default Key Bindings").

= Status window

 execute - prompt user for a function or macro. The tab key acts as a
   "completion" command.
 status::msg <string> - prints 'string' on the status line.  (This
    should be used in preference to the older 'message' which conflicts
    with Tk).
 statusPrompt <prompt> [<func>] - Prompt in the status window. If 'func' 
    is present, call this routine at each key-press with the current contents
    of the status line and the key, insert into statusline whatever is returned
    by the func.  Command-v pastes the current (<80 char) clipboard contents on
    the status line.  Also see 'status::prompt' which is more flexible.

= Filesystem

 getFileInfo <file> <arr> - Given a file name, creates an array called 
    'arr' in the current context, containing fields 'created', 'creator',
    'modified', 'type', 'datalen', and 'resourcelen'.  'created' and 'modified'
    are in a form suitable for the command 'mtime'.
 glob [-i] [-t <TYPE>] [-c <CRTR>]
    The original glob provided by the UNIX version of tcl was not quite
    adequate for the more complex Macintosh file system.  Issues such as
    invisible file handling, Finder type and creator filtering, and space
    handling in file names.  Release 6 of tcl has dealt with the original
    problem with spaces in filenames, but the following options are provided to
    deal with additional Macintosh issues.

    Anyway, the new glob now takes several options. They are:

      -i	           This option causes glob to list invisible files also.
      -t TYPE	      This option causes glob to only list file with the 
                    indicated Finder file typeTYPE. This option may be 
                    used with the -c option.
      -c CRTR	      This option causes glob to only list file with the 
                    indicated Finder file creatorCRTR. This option may 
                    be used with the -t option.
                    
    Also note that the original glob would skip dot files (i.e., file names the
    begin with a period) in the listing, unless the pattern began with a period.
    Tickle extends this concept one step further on the Macintosh, and skips
    spot files (i.e., file names that begin with ''), unless the pattern starts
    with a spot.
 ls - unix style directory listing, described in "Shells"
 pwd - return the current working directory, ending in a colon.
 setFileInfo <file> <field> [arg] - set some information for files.
    Settable fields are 'modified', 'created', 'creator', and 'type'.  All take
    an argument except 'resourcelen' which just removes the resource fork. 
    'file' is a complete pathname.
 wc <file>... - counts chars, words, lines of input files.

= Debugging

 dumpDebug - return the current debug stack.
 echo <string>* - echo the strings (used in shells).
 evaluate - evaluates hilited text, or entire window if nothing is hilited.
   'evaluat'ing means that whatever bindings or macro definitions are present
   in the evaluated text take effect
 shell - open the Tcl shell.
 traceDump - 
 traceFunc <args> - manipulate traces of functions for debugging.  'args' 
    can be 'on' 'off' or 'status'.

      traceFunc on <proc> <win> - Trace 'proc', send output to 'win'. 
      traceFunc off             - Turn function tracing off.
      traceFunc status          - Display current tracing status.

= Colours

 dumpColors - dump current foreground and background colors into the
    current buffer in Alpha-readable format.
 getColors - returns list of colors/hypertext for current document. 
    Format is list of lists, each sublist consisting of file offset, color
    index, and possibly a hypertext command.
 insertColorEscape <pos> <color ind> [hypertext func] - Create a color 
    or style "point" for documentation purposes.  Look at the file
    "colorsMenu.tcl" for examples.  The hypertext func is only used when the
    "point" is underlined.  See 'getColors' for info about the current file. 
    You should now use the proc: text::color and the proc: text::hyper instead
    of this function.
 regModeKeywords [options] <mode> <keyword list> - Set keywords and comments
    that Alpha can recognize to color them.  Specifically, in mode <mode>,
    every keyword specified in the list is colored non-black (blue, by
    default).  Comments, if specified by '-e' or '-b' below, are colored red by
    default.  	Keywords must be less than 20 characters long in Alpha7.

      -a              Keywords will be *added* to existing mode keywords.
                      The new keywords can be a different color than older
                      keywords.  This flag can also be used to modify other
                      attributes.
      -b <beg> <end>  Specify a pair of strings that bracket a comment.
      -c <color>      Comment color.
      -e <commentstr> Specify a string that begins comments that last to 
                      the end of the line.
      -f <color>      'Function' color, which will color any word preceding '('
      -i <char>       Specify a character to display differently.
                      Commonly used for curly braces, etc.
      -I <color>      Color of above characters.
      -k <color>      Keyword color.
      -m <c>          Specify a magic character. Every word beginning with the 
                      magic character is a keyword.
      -s <color>      String color. Alpha7 can color single-line strings only,
                      using the simple heuristic of assuming the first two double
                      quotes constitute a string.

 removeColorEscapes - remove color escapes from topmost window.

= Keyboard macros

 iterationCount - allows actions to be repeated many times. 
	"control-u 44 =" inserts 44 '='s into current window.  Also can be used to
	execute any function or macro (including the keyboard macro) many times. 
	Defaults to 4.
 macro::current - return the most recently recorded keyboard macro as a proc.
 macro::endRecording - stop recording keyboard macro
 macro::execute - execute the current keyboard macro
 macro::startRecording - start recording keyboard macro
 macro::recording - are we currently recording?

= Time related

 cvttime - convert input time to/from some epoch (+/- 0x7c25b080).
 mtime <time> [long|short|abbrev] - return a date and time string using 
    the Macintosh International Utilities.  The long/short/abbrev specification
    corresponds to the date.  These are the following formats:

      short     3/16/92 9:20:46 PM
      abbrev    Mon, Mar 16, 1992 9:20:49 PM
      long      Monday, March 16, 1992 9:20:43 PM

    The returned value actually is in the form of a list.  To get text as
    above, run the result through 'join', as in "join [mtime [now] short]".
 now - return the current time as Macintosh seconds. This is the number
    of seconds that have elapsed since Midnight Jan 1, 1904.
 ticks - return the current TickCount. Ticks are 60ths of a seconds.
    TickCount is the number of ticks since the Macintosh was started.  The
    command:

      puts stdout [expr "[ticks] / 60"]

    will print the number of seconds since the Macintosh was booted.

= Marks

 createTMark <name> <pos> - create a temporary 'mark' at location 'pos'. 
 getMark - return the current mark.
 getNamedMarks [-w <win>] [-n] - return list of all permanent marks
    in open files.  Each element of a list describes one mark as a sublist of
    the mark's name, the complete pathname of the mark's file, the position of
    the first character in the first line displayed, the current position, and
    the end of the selection if text is hilited, or the current position again
    if there is no hilited section.  '-w' allows window name to be applied as
    filter, '-n' means only names will be returned.
 getTMarks - return a list of temporary marks. Each item of the returned 
    list is a sublist containing the mark name, the complete pathname of the
    mark, and the start and finish of the selection named by the mark.  The
    following is an example of the result:

      {{temp1 External:file.c 1312 1315} {temp2 Internal:it.h 111 111}} 

 removeNamedMark [-w window] [-n name] - remove a mark previously set by 
     'setNamedMark'.  If neither -w nor -n are specified, presents the user with
     a dialog containing all marks from all open windows.  If only -w is
     specified, presents the user with a dialog containing all marks from the
     specified window.  If both -w and -n are specified, the mark 'name' is
     removed from 'window'.  If only -n is specified, the mark 'name' is removed
     from the current window.
 removeTMark <name> - remove temporary mark.
 setNamedMark [name disp pos end] - set named mark. If optional arguments are 
    present, the mark is created without prompting user.  'disp' is the
    character position of the start of the first line to be displayed, while
    'pos' and 'end' bracket the text to be selected.


= Remaining commands (in alphabetical order) -- 

  some of these still need placing in other sections of this document.

 abortEm - aborts whatever is currently happening
 addAlphaChars <chars> - Add <chars> to the list of characters that internally 
    are caught by the 'isalnum' and 'isalpha' calls.  Can be used to augment
    the list of characters that the \w pattern in a regular expression responds
    to.  Use w/ care.
 alloced - output information on memory allocation.
 alphaCreateTagFile - In "filesets.tcl":

       if {![string length [info commands alphaFindTag]]} {
           rename findTag alphaFindTag
           rename createTagFile alphaCreateTagFile
       }

    I think they are renamed to allow the possibility of fileset-specific tag
    finding procedures.  I've never found tags worked very well for me,
    although in principle they sounded very useful, so I've never experimented
    with this at all. (Vince Darley)
 alphaFindTag - see 'alphaCreateTagFile'.
 beep [-volume num] [-list | sndName]? where -volume and -list are switches,
    while num and sndName are variables. Example:  
      beep -volume 3 "click in set 5"
    will play at volume 3 the sound named "click in set 5" in the Alpha's snd
    resource.  Any sound stored in that resource can be used as well, so feel
    free to paste a sound (with ResEdit) in the snd resource to have it
    available.
 breakIntoLines <string> - return 'string' with carriage returns and spaces
    inserted to satisfy 'leftFillColumn' and 'fillColumn' variables.
 createTagFile - searches all files in current file set and saves the
    locations of any function declarations in a file called 'cTAGS'.
 findTag - prompt user for a function name and attempt to use the file 'cTAGS'
    to locate the function's definition
 init - set noRemapOption and startWithNew, whatever that means.
 linkVar - link a Tcl variable to a preexisting internal variable of the
    same name.
 pageSetup - display the printing PageSetup dialog.
 print - print front window
 printRegistration - dump a registration form to the current printer.
 quit - quits ALPHA
 redo - redo the next action that has been undone but not redone
 restoreVars - 
 saveVars - 
 status - show some debugging info in the status bar.
 subst - a non-command-invoking sibling of 'eval'.  Brent Welsh has a few
   paragraphs on it in "Practical Programming in Tcl and Tk" at the end of
   Chapter 10 <http://www.beedub.com/book>.
 undo - undo the last action that has not been undone
 version - Return string of the form "Alpha Version 5.31, Feb. 15, 1993".
 watchCursor - turns the cursor into a a watch cursor.

= Uncommon/unused commands -- probably best to avoid using these.

 abbrev <label> <string> [<mode>] - register a label for <string>. 
    See 'execAbbrev' below.
 currentPosition - display current and total bytes.
 execAbbrev - look at current word and tries to expand it. Labels are 
    specified using 'abbrev'.
 fileInfo - prompt for a file, and display type, creator, sizes of both
    data and resource forks, last modification time, and creation time
 fileMenu - 
 fileRemove - prompt for a file, and remove it
 freeMem - give a rough approximation of the current memory reserves of ALPHA
 getPathName - prompt the user with an SFGetFile dialog and return 
    complete pathname.
 icURL <URL> - passes arg to Internet Config, if present. Error if not 
    present.  You should use 'url::execute' instead (icURL is deprecated).
 insertFile - prompt for a file name and insert the corresponding file into
    the current window. Not undoable.
 insertPathName - present the user w/ a SFGetFIle dialog and paste the
    complete path-name of the chosen file into the current window
 largestPrefix <list> - return the longest prefix contained in all 
    strings of 'list'.
 substituteVars <string> - Take a single string and substitute for all
    variables inside it, regardless of depth.  Unfortunately, you currently
    need to make 'global var' declarations in the proc you call this for each
    'var' that might need to be substituted in the string (see "proc.tcl" for
    examples).

= Obsolete (and possibly buggy).  These WILL be removed in Alpha 8.

 bind - Use 'Bind' instead.
 coerce - obsolete
 copyFile - obsolete
 cp <fromName>+ <toName> - copy the file fromName and name the new file toName, 
	overwriting any existing file.  This command copies both data forks, and
	the Finder information.  'file copy' is the prefered means of carrying out
	copies in Alpha 7.0 or newer.
 kt - obsolete
 mkdir <name> - create a directory (folder) named 'name' in the current
	directory.  Use 'file mkdir' instead.
 moveFile <fromName> <toName> - move the file fromName to toName, overwriting
	any existing file.  The move can not be made across volume (disk drives)
	boundaries.  Use 'file copy/delete' instead.
 postHigh - obsolete
 removeFile <fileName> - delete the file or folder 'fileName'.
	Use 'file delete' instead.
 replaceAllOld - obsolete version of replaceAll. 
 rmdir <dirname> - remove a directory (folder).  'file delete <dirname>' is 
	the prefered means of deleting directories in Alpha 7.0 or newer.
 setCompiler - obsolete
 unbind - Use 'unBind' instead.
 winFuncTitle - I think this used to be used in old versions of Alpha (5.*?)
	in which the functions/marks popup menu (currently near the top-right
	corner of Alpha's windows) used to be _on_ the window titlebar (to the left
	of the zoombox).  Each of the two titlebar-popup-button had a space for 4
	characters in the Monaco 9pt font, and the default funcTitle was "func" and
	the default markTitle was "mark", I think.  Anyway that's completely
	obsolete now. (Mark Nagata)
 xtclcmd [-f filename] <cmdname> [argument_list]* -  load the external command
	cmdname and pass it the argument list [ cmdname argument_list...  ]. 
	External command are code resources of type XTCL. They may be located in
	the resource fork of the tickle application, or they may be located in a
	file named XTCL File in the same directory as the tickle application.  If
	the optional -f filename is included, the external command will first be
	loaded from filename before the other two files.  See the appendix for a
	detailed description of the external tcl command interface.  See the
	accompanying sources for an example of writing an XTCL.


